home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / utilities / text / tec10.lha / TEC.doc next >
Encoding:
Text File  |  1994-05-24  |  9.7 KB  |  255 lines
  1.  
  2.                           The Text Converter - TEC 1.0
  3.  
  4.                  (c) 1994 Martin Mares, MJSoft System Software
  5.  
  6. ================================================================================
  7.  
  8.  
  9. Copyright:
  10. ----------
  11.  
  12.   TEC and its documentation are Copyright (c) Martin Mares, MJSoft System
  13. Software, Prague, Czech Republic.
  14.  
  15.    This  archive  can be freely redistributed, as long as all of its files are
  16. included   in   their  original  form  without  any  additions,  deletions  or
  17. modifications, and no more than a nominal fee is charged for its distribution.
  18. All  copyright  notices  in  the programs and accompanying documentation files
  19. must  remain  on  their places.  Also '.displayme' and other similar files may
  20. not be added.  This is generally known as FREEWARE.
  21.  
  22.    Special  permission is given to Fred Fish to distribute this program on his
  23. "Fish Disks".
  24.  
  25.    This  software  is  provided  "AS  IS" without warranty of any kind, either
  26. expressed  or implied.  The author is not responsible for any damage caused by
  27. it.
  28.  
  29.  
  30. Introduction
  31. ------------
  32.  
  33.    Almost any programmer sometimes needs to convert some text file to another
  34. one (for example AmigaGuide to plain text or stripping of ANSI-sequences...) and
  35. it usually results in writing of a small utility to do such a job.  These
  36. utilities are very similar to each other and most of them contain the same
  37. routines for input and output buffering, because the buffered I/O provided by
  38. the dos is terribly slow.  This is the reason why I decided to write TEC.
  39.  
  40.    TEC is a simple tool designed to simplify many text conversion tasks. It
  41. acts as a one-input and one-output state machine with one internal string
  42. register, therefore it would be better to use some other programs (awk) for
  43. field-oriented conversion.
  44.  
  45.    TEC requires OS 2.04 or higher and the ss.library.
  46.  
  47.    TEC is pure and can be made resident.
  48.  
  49.  
  50. Invocation:
  51. -----------
  52.  
  53.    TEC may be started only from the CLI and has the following parameters:
  54.  
  55.   FILTER/M/A - a list of filter programs to be applied.  If any of them is
  56. enclosed in single quotes, it will be interpreted as an one-line program.  If
  57. it's a file name, default extension '.tec' will be appended.  The input file
  58. will be processed by the first filter and passed as an input of the second
  59. filter ...  the output of the last filter will be written to the output file.
  60. In many cases, single filter is enough to do the job.
  61.  
  62.    FROM/K, TO/K - names of source and destination file. If they're
  63. omitted, standard input/output is used instead.
  64.  
  65.    BUF/K/N - buffer size in bytes. Default=16384 bytes. Minimally 16 bytes.
  66.  
  67.    The conversion may be stopped in any time by pressing CTRL-C or by sending
  68. the break-C signal to it.
  69.  
  70.  
  71. The language:
  72. -------------
  73.  
  74.    There are listed the basic elements of the language:
  75.  
  76.   - comments - everything from '%' to end of line is ignored (only when the
  77. percent sign is not a part of character or string constant)
  78.   - separators - semicolon and the end of line character
  79.   - characters - (a) specified by decimal code
  80.          (b) specified by hexadecimal code (preceeded by $)
  81.          (c) character constant (enclosed in single quotes). It may
  82.              contain escape characters (see below).
  83.   - keywords - COPY,MSG,PUT,EOF,STOP,FAIL,NOCASE,ELSE,CLR,ADD,PUTS,CAT,SWITCH,
  84.                CSWITCH,USE,GLOBAL,CASE,BACK.
  85.   - state names - sequences of letters, digits and underscores, which don't
  86. start with a digit.
  87.   - strings - sequences of any characters (including escapes) enclosed in double
  88. quotes. They cannot exceed one line unless the end of line is immediately
  89. preceeded by backslash (ignored escape sequence).
  90.   - escape sequences - beginning with backslash
  91.  
  92.     \t - tab    \n - newline    \\ - backslash
  93.     \' - '        \r - return    \e - escape (char #27)
  94.     \" - "
  95.  
  96.     in addition to these rules, backslash followed immediately by newline is
  97. ignored allowing long commands to be split to more lines of source text.
  98.  
  99.    The language itself is not case-sensitive, but the rules written in it
  100. usually are.
  101.  
  102.  
  103. Program:
  104. --------
  105.  
  106.    Each program consists of so called states. The interpreter can be in exactly
  107. one state at the moment. The conversion is started in the first state regardless
  108. to its name.
  109.  
  110.    It isn't necessary to specify a name of the first state unless there is
  111. a GLOBAL before it (see somewhere else what the GLOBAL is).
  112.  
  113.    'Simple' state definition:
  114.    --------------------------
  115.  
  116. <state name>: <commands>
  117.  
  118.   When this type of state is entered, the <commands> are executed and
  119. the program is stopped unless the command sequence ends with name of another
  120. state to continue the program by. The commands may be separated by semicolons or
  121. newlines, but it doesn't affect their execution in any way.
  122.  
  123.    'Complex' state definition:
  124.    ---------------------------
  125.  
  126. <state name>: [<init commands>] [USE <state>] {<charlist> <commands> <sep>}
  127. [ELSE <commands>]
  128.  
  129.    In this case, the <init commands> are executed, then one character from input
  130. is read and the interpreter finds corresponding <commands> for such a character.
  131. If there exist no <charlist> containing recent input character, the <commands>
  132. after ELSE are executed. Init commands may be separated by <sep>, but it doesn't
  133. affect their execution in any way.
  134.  
  135.    <charlist> - a list of characters separated by white spaces. May contain the
  136. EOF keyword which equals to END OF FILE condition.
  137.  
  138.    <commands> - any command list (see below).  If it is not specified, the input
  139. character is thrown away.  If no next state is specified, the current state is
  140. used again.  These rules have exception:  The default action for EOF is the STOP
  141. command causing immediate stopping of execution.
  142.  
  143.    <sep> - separator - semicolon or end of line
  144.  
  145.    The ELSE part may be omitted - automatically replaced by ELSE COPY (the
  146. current character is copied to output stream without any changes).
  147.  
  148.    The USE keyword causes the current character conditions to be derived from
  149. given state, which may contain ONLY the character conditions (it means NO
  150. initial commands). Warning: the ELSE <commands> phrase has _no_effect_, because
  151. all character conditions are set from the state we derive from. Another warning:
  152. If there are some conditions with no next state (using the same state as the
  153. next one), they will contain the original state as destination (they got fixed
  154. before the USE command). Therefore
  155.     alpha: '1' '2' put '@'
  156.     gamma: use alpha '4' put '!' else put '>'
  157.    is equivalent to:
  158.     alpha: '1' '2' put '@'
  159.     gamma: '1' '2' put '@' alpha ; '4' put '!' gamma ; else copy alpha
  160.    As you can see above, the USE command has very limited use and will be
  161. probably improved in future releases.
  162.  
  163.    Command lists:
  164.    --------------
  165.  
  166. {<command>} [<state name>]
  167.  
  168.    It means that the commands have to be executed in their natural order and
  169. then the converter has to continue with <state name>, if there's any.
  170.  
  171.  
  172. Basic commands:
  173. ---------------
  174.  
  175.    COPY - copy recently read character into output stream
  176.    PUT <character> - copy given character into output stream
  177.    > <character> - synonym to PUT
  178.    STOP - stop conversion
  179.    FAIL - stop conversion and exit with RC=10
  180.    CLR - clear contents of the string buffer
  181.    ADD - add recently read character at the end of the string buffer (maximally
  182. 255 characters)
  183.    PUTS - put contents of string buffer into output stream
  184.    BACK - push recently read character back to the input stream. You may do it
  185. only ONCE unless the character is read again.
  186.  
  187.  
  188. Other commands:
  189. ---------------
  190.  
  191.    PUT <string> - copy string into output stream
  192.    CAT <string> - add string at the end of the string buffer
  193.    MSG <string> - copy string into standard output
  194.  
  195.  
  196. Switching:
  197. ----------
  198.  
  199.    You may test contents of the string buffer by the SWITCH and CSWITCH. These
  200. tests may appear only in <init commands> of a state. The only difference between
  201. SWITCH and CSWITCH is that CSWITCH is case-sensitive.
  202.  
  203.    SWITCH {<string> <state>} ELSE <the command list continues here>
  204.  
  205.    The interpreter compares current contents of string buffer with the strings
  206. in the SWITCH command (in first-to-last order). Then it goes to <state> defined
  207. for first string which is equal to the buffer. If no string matches the buffer,
  208. the execution continues after the ELSE keyword.
  209.  
  210.    For example: CSWITCH "aaa" aaa ; "bbb" bbb ; "aaa" ccc ELSE STOP never calls
  211. the state ccc.
  212.  
  213.  
  214. Global definitions:
  215. -------------------
  216.  
  217.    It's possible to write some conditions affecting read characters in ALL
  218. states (but these conditions may be overriden in some states by simple
  219. redefinition of them). These global conditions are called GLOBALs and are
  220. defined before the first state of the program.
  221.  
  222.    GLOBAL {<charlist> [<basic command>] [<state>]} [ELSE <basic command>
  223. <state>]
  224.  
  225.    There are two differences between standard state definitions and the GLOBALs:
  226.  (1) The GLOBALs can contain only basic commands (not the more complex ones).
  227.  (2) The references to current state are not fixed immediately, so you can
  228. say that you want to convert each 'A' into 'a' without changing current state.
  229. This is the reason why GLOBALs are usually more preferable than USEs.
  230.  
  231.  
  232. Case senstivity:
  233. ----------------
  234.  
  235.    All character comparisons are case-sensitive.
  236.  
  237.    If you say NOCASE before <charlist>, each letter in each <charlist> in
  238. current state (unless you say CASE) will be automatically converted to both
  239. cases ('a' becomes 'a' 'A').
  240.  
  241.  
  242. Final words:
  243. ------------
  244.  
  245.    Send bug reports, comments and nice conversion tables to
  246.                         mjsoft@k332.feld.cvut.cz.
  247.  
  248.    This language is very simple and probably doesn't allow all things you need.
  249. The command set will be extended in some future version (if I will have some
  250. free time to do it), numeric registers and more string registers will be added,
  251. USE mechanism will be extended to be slightly more user-friendly and ... (mail
  252. me what would you like to be added).
  253.  
  254.    Thanks to Short Software for some good ideas.
  255.